home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / unixSyscall / RCS / sigvec.man,v < prev    next >
Text File  |  1990-12-13  |  10KB  |  368 lines
  1. head     1.3;
  2. branch   ;
  3. access   ;
  4. symbols  ;
  5. locks    ; strict;
  6. comment  @@;
  7.  
  8.  
  9. 1.3
  10. date     90.12.13.17.08.18;  author shirriff;  state Exp;
  11. branches ;
  12. next     1.2;
  13.  
  14. 1.2
  15. date     88.12.31.12.10.42;  author ouster;  state Exp;
  16. branches ;
  17. next     1.1;
  18.  
  19. 1.1
  20. date     88.12.31.11.58.13;  author ouster;  state Exp;
  21. branches ;
  22. next     ;
  23.  
  24.  
  25. desc
  26. @@
  27.  
  28.  
  29. 1.3
  30. log
  31. @Added information on handler to the man page.
  32. @
  33. text
  34. @.\" Copyright (c) 1980 Regents of the University of California.
  35. .\" All rights reserved.  The Berkeley software License Agreement
  36. .\" specifies the terms and conditions for redistribution.
  37. .\"
  38. .\"    @@(#)sigvec.2    6.3 (Berkeley) 1/8/86
  39. .\"
  40. .TH SIGVEC 2 "January 8, 1986"
  41. .UC 4
  42. .ie t .ds d \(dg
  43. .el .ds d \z'|+'
  44. .ie t .ds b \(bu
  45. .el .ds b @@
  46. .SH NAME
  47. sigvec \- software signal facilities
  48. .SH SYNOPSIS
  49. .nf
  50. .B #include <signal.h>
  51. .PP
  52. .B struct sigvec {
  53. .B    int    (*sv_handler)();
  54. .B    int    sv_mask;
  55. .B    int    sv_flags;
  56. .B };
  57. .PP
  58. .B sigvec(sig, vec, ovec)
  59. .B int sig;
  60. .B struct sigvec *vec, *ovec;
  61. .fi
  62. .SH DESCRIPTION
  63. The system defines a set of signals that may be delivered to a process.
  64. Signal delivery resembles the occurence of a hardware interrupt:
  65. the signal is blocked from further occurrence, the current process 
  66. context is saved, and a new one is built.  A process may specify a
  67. .I handler
  68. to which a signal is delivered, or specify that a signal is to be 
  69. .I blocked
  70. or
  71. .IR ignored .
  72. A process may also specify that a default action is to be taken
  73. by the system when a signal occurs.
  74. Normally, signal handlers execute on the current stack
  75. of the process.  This may be changed, on a per-handler basis,
  76. so that signals are taken on a special
  77. .IR "signal stack" .
  78. .PP
  79. All signals have the same
  80. .IR priority .
  81. Signal routines execute with the signal that caused their
  82. invocation
  83. .IR blocked ,
  84. but other signals may yet occur.
  85. A global 
  86. .I "signal mask"
  87. defines the set of signals currently blocked from delivery
  88. to a process.  The signal mask for a process is initialized
  89. from that of its parent (normally 0).  It
  90. may be changed with a
  91. .IR sigblock (2)
  92. or
  93. .IR sigsetmask (2)
  94. call, or when a signal is delivered to the process.
  95. .PP
  96. When a signal
  97. condition arises for a process, the signal is added to a set of
  98. signals pending for the process.  If the signal is not currently
  99. .I blocked
  100. by the process then it is delivered to the process.  When a signal
  101. is delivered, the current state of the process is saved,
  102. a new signal mask is calculated (as described below), 
  103. and the signal handler is invoked.  The call to the handler
  104. is arranged so that if the signal handling routine returns
  105. normally the process will resume execution in the context
  106. from before the signal's delivery.
  107. If the process wishes to resume in a different context, then it
  108. must arrange to restore the previous context itself.
  109. .PP
  110. When a signal is delivered to a process a new signal mask is
  111. installed for the duration of the process' signal handler
  112. (or until a
  113. .I sigblock
  114. or
  115. .I sigsetmask
  116. call is made).
  117. This mask is formed by taking the current signal mask,
  118. adding the signal to be delivered, and 
  119. .IR or 'ing
  120. in the signal mask associated with the handler to be invoked.
  121. .PP
  122. .I Sigvec
  123. assigns a handler for a specific signal.  If
  124. .I vec
  125. is non-zero, it
  126. specifies a handler routine and mask
  127. to be used when delivering the specified signal.
  128. Further, if the SV_ONSTACK bit is set in
  129. .I sv_flags,
  130. the system will deliver the signal to the process on a
  131. .IR "signal stack" ,
  132. specified with
  133. .IR sigstack (2).
  134. If 
  135. .I ovec
  136. is non-zero, the previous handling information for the signal
  137. is returned to the user.
  138. .PP
  139. The following is a list of all signals
  140. with names as in the include file
  141. .RI < signal.h >:
  142. .LP
  143. .nf
  144. .ta \w'SIGMIGHOME 'u +\w'15*  'u
  145. SIGHUP    1    hangup
  146. SIGINT    2    interrupt
  147. SIGDEBUG    3*    force process into debuggable state
  148. SIGILL    4*    illegal instruction
  149. SIGTRAP    5*    trace trap
  150. SIGIOT    6*    IOT instruction
  151. SIGEMT    7*    EMT instruction
  152. SIGFPE    8*    floating point exception
  153. SIGKILL    9    kill (cannot be caught, blocked, or ignored)
  154. SIGMIG    10    migrate process (cannot be caught, blocked, or ignored)
  155. SIGSEGV    11*    segmentation violation
  156. SIGSYS    12*    bad argument to system call
  157. SIGPIPE    13    write on a pipe with no one to read it
  158. SIGALRM    14    alarm clock
  159. SIGTERM    15    software termination signal
  160. SIGURG    16\*b    urgent condition present on socket
  161. SIGSTOP    17\*d    stop (cannot be caught, blocked, or ignored)
  162. SIGTSTP    18\*d    stop signal generated from keyboard
  163. SIGCONT    19\*b    continue after stop (cannot be blocked)
  164. SIGCHLD    20\*b    child status has changed
  165. SIGTTIN    21\*d    background read attempted from control terminal
  166. SIGTTOU    22\*d    background write attempted to control terminal
  167. SIGIO    23\*b    i/o is possible on a descriptor (see \fIfcntl\fP(2))
  168. SIGXCPU    24    cpu time limit exceeded (see \fIsetrlimit\fP(2))
  169. SIGXFSZ    25    file size limit exceeded (see \fIsetrlimit\fP(2))
  170. SIGVTALRM    26    virtual time alarm (see \fIsetitimer\fP(2))
  171. SIGPROF    27    profiling timer alarm (see \fIsetitimer\fP(2))
  172. SIGWINCH    28\*b    window size change
  173. SIGMIGHOME    29    migrate back to home node (cannot be caught, blocked, or ignored)
  174. SIGUSR1    30    user defined signal 1
  175. SIGUSR2    31    user defined signal 2
  176. .fi
  177. .PP
  178. The starred signals in the list above cause the process to enter DEBUG
  179. state if not caught or ignored.
  180. .PP
  181. Once a signal handler is installed, it remains installed
  182. until another
  183. .I sigvec
  184. call is made, or an 
  185. .IR execve (2)
  186. is performed.
  187. The default action for a signal may be reinstated by setting
  188. .I sv_handler
  189. to SIG_DFL; this default is termination
  190. (with a core image for starred signals)
  191. except for signals marked with \*b or \*d.
  192. Signals marked with \*b are discarded if the action
  193. is SIG_DFL; signals marked
  194. with \*d cause the process to stop.
  195. If
  196. .I sv_handler
  197. is SIG_IGN the signal is subsequently ignored,
  198. and pending instances of the signal are discarded.
  199. .PP
  200. If a caught signal occurs during certain system calls,
  201. the call is normally restarted.
  202. The call can be forced to terminate prematurely with an
  203. EINTR error return by setting the SV_INTERRUPT bit in
  204. .I sv_flags.
  205. The affected system calls are
  206. .IR read (2)
  207. or
  208. .IR write (2)
  209. on a slow device (such as a terminal; but not a file)
  210. and during a
  211. .IR wait (2).
  212. .PP
  213. After a
  214. .IR fork (2)
  215. or
  216. .IR vfork (2)
  217. the child inherits
  218. all signals, the signal mask, the signal stack,
  219. and the restart/interrupt flags.
  220. .PP
  221. .IR  Execve (2)
  222. resets all
  223. caught signals to default action and
  224. resets all signals to be caught on the user stack.
  225. Ignored signals remain ignored;
  226. the signal mask remains the same;
  227. signals that interrupt system calls continue to do so.
  228. .SH NOTES
  229. The mask specified in 
  230. .I vec
  231. is not allowed to block SIGKILL, SIGSTOP, or SIGCONT.  This
  232. is done silently by the system.
  233. .PP
  234. The SV_INTERRUPT flag is not available in 4.2BSD,
  235. hence it should not be used if backward compatibility is needed.
  236. .SH "RETURN VALUE
  237. A 0 value indicated that the call succeeded.  A \-1 return value
  238. indicates an error occurred and
  239. .I errno
  240. is set to indicated the reason.
  241. .SH ERRORS
  242. .I Sigvec
  243. will fail and no new signal handler will be installed if one
  244. of the following occurs:
  245. .TP 15
  246. [EFAULT]
  247. Either
  248. .I vec
  249. or 
  250. .I ovec
  251. points to memory that is not a valid part of the process
  252. address space.
  253. .TP 15
  254. [EINVAL]
  255. .I Sig
  256. is not a valid signal number.
  257. .TP 15
  258. [EINVAL]
  259. An attempt is made to ignore or supply a handler for SIGKILL
  260. or SIGSTOP.
  261. .TP 15
  262. [EINVAL]
  263. An attempt is made to ignore SIGCONT (by default SIGCONT
  264. is ignored).
  265. .SH "SEE ALSO"
  266. kill(1),
  267. ptrace(2), kill(2),
  268. sigblock(2), sigsetmask(2), sigpause(2),
  269. sigstack(2), sigvec(2), setjmp(3), siginterrupt(3), tty(4)
  270. .SH BUGS
  271. This manual page is still confusing.
  272. .SH NOTES
  273. The handler routine can be declared:
  274. .nf
  275. .PP
  276. .B    void handler(sig, code, scp, addr)
  277. .B    int sig,code;
  278. .B    struct sigcontext *scp;
  279. .B    char *addr;
  280. @
  281.  
  282.  
  283. 1.2
  284. log
  285. @Document Sprite changes.
  286. @
  287. text
  288. @d239 8
  289. @
  290.  
  291.  
  292. 1.1
  293. log
  294. @Initial revision
  295. @
  296. text
  297. @d111 1
  298. a111 1
  299. .ta \w'SIGVTALRM 'u +\w'15*  'u
  300. d114 1
  301. a114 1
  302. SIGQUIT    3*    quit
  303. d121 1
  304. a121 1
  305. SIGBUS    10*    bus error
  306. d140 1
  307. d145 2
  308. a146 2
  309. The starred signals in the list above cause a core image
  310. if not caught or ignored.
  311. a236 55
  312. .SH "NOTES  (VAX-11)"
  313. The handler routine can be declared:
  314. .PP
  315.     handler(sig, code, scp)
  316.     int sig, code;
  317.     struct sigcontext *scp;
  318. .PP
  319. Here
  320. .I sig
  321. is the signal number, into which the hardware faults and traps are
  322. mapped as defined below. 
  323. .I Code
  324. is a parameter that is either a constant
  325. as given below or, for compatibility mode faults, the code provided by
  326. the hardware (Compatibility mode faults are distinguished from the
  327. other SIGILL traps by having PSL_CM set in the psl).
  328. .I Scp
  329. is a pointer to the
  330. .I sigcontext
  331. structure (defined in
  332. .RI < signal.h >),
  333. used to restore the context from before the signal.
  334. .PP
  335. The following defines the mapping of hardware traps to signals
  336. and codes.  All of these symbols are defined in
  337. .RI < signal.h >:
  338. .LP
  339. .ta \w'     Floating/decimal divide by zero   'u +\w'15*  'u +8n
  340. .nf
  341.    Hardware condition    Signal    Code
  342.  
  343. Arithmetic traps:
  344.    Integer overflow    SIGFPE    FPE_INTOVF_TRAP
  345.    Integer division by zero    SIGFPE    FPE_INTDIV_TRAP
  346.    Floating overflow trap    SIGFPE    FPE_FLTOVF_TRAP
  347.    Floating/decimal division by zero    SIGFPE    FPE_FLTDIV_TRAP
  348.    Floating underflow trap    SIGFPE    FPE_FLTUND_TRAP
  349.    Decimal overflow trap    SIGFPE    FPE_DECOVF_TRAP
  350.    Subscript-range    SIGFPE    FPE_SUBRNG_TRAP
  351.    Floating overflow fault    SIGFPE    FPE_FLTOVF_FAULT
  352.    Floating divide by zero fault    SIGFPE    FPE_FLTDIV_FAULT
  353.    Floating underflow fault    SIGFPE    FPE_FLTUND_FAULT
  354. Length access control    SIGSEGV
  355. Protection violation    SIGBUS
  356. Reserved instruction    SIGILL    ILL_RESAD_FAULT
  357. Customer-reserved instr.    SIGEMT
  358. Reserved operand    SIGILL    ILL_PRIVIN_FAULT
  359. Reserved addressing    SIGILL    ILL_RESOP_FAULT
  360. Trace pending    SIGTRAP
  361. Bpt instruction    SIGTRAP
  362. Compatibility-mode    SIGILL    hardware supplied code
  363. Chme    SIGSEGV
  364. Chms    SIGSEGV
  365. Chmu    SIGSEGV
  366. .fi
  367. @
  368.